Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/lists/gem/l_0799/667

Internet Message Format | 1994-08-27 | 10.7 KB

Date: Sat, 2 Jul 94 00:29 CDT
From: [e-mail] (Evan K. Langlois)
To: [e-mail]
Subject: Dialogs & Extra Buttons
Precedence: bulk

  The following is for dialog boxes, since these came up.  Dialogs should
use the exact same hot-keys and editing keys that the application uses.
This set of rules is largely from the ATARI Compendium and ATARI developer
guidelines.  You should get these and read them.  Just because it works on
your system, doesn't mean it is correct.  Failure to follow all programming
guidelines can result in "quirks", hardware dependance, messy window redraw,
or dead-locked applications (ex.  Don't call wind_update (BEG_UPDATE) before
evnt_multi)!  A complete list of all guidelines is beyond the scope of the
GEM-List.  The GEM-List only supplements ATARI's documentation.

  If you have AES 3.4 or greater, you should check and see what features
are present in the system using appl_getinfo().


Guidelines for Dialog Boxes :
=============================

  Use these guidelines for all Dialog Boxes -

  o  Prior to drawing a dialog and calling form_do(), call wind_update
(BEG_UPDATE).  Do not call wind_update (END_UPDATE) until the dialog is
removed and user-interaction is complete.

  o  If a dialog box controls a physical attribute (fill style, text font,
etc), then the dialog box should contain a sample area, where changes are
shown before the user exits the dialog functions.

  o  Dialogs that position themselves over the mouse cursor, or in the
center of the active window should allow this feature to be disabled as it
annoys some users.

  o  Dialogs boxes should present buttons in order (left-to-right or top-down)
of "Ok", "Cancel", .. other buttons .., "Help".

  o  Unfolding dialogs should use the symbol ">>" on a button to show which
button unfolds the dialog (for "advanced" users) and the "<<" symbol should
return the dialog to its original form.  ex : "More >>" changes to "<< Less"
when the dialog expands; "Options >>" changes to "<< Options"

  o  If you directly modify a dialog with VDI calls, make you you call
objc_offset first, since the user may have moved the dialog.  If you have
an active-scrollbar, use objc_offset once when you detect the mouse down
and update your display when needed using VDI bit-blit functions until
the mouse is released.  A double-click on the slider "knob" should display
an alert to let the user choose between active and passive scrollers when
you wish to allow an active scroller.


Over-riding FORM_DO :
---------------------

  Use these guidelines to construct your own form_do().  It should emulate
form_do() EXACTLY!  I recommend that you use form_do() and not write
your own handler for the majority of user interaction, allowing a custom
global form_do() replacement to be used to keep interfaces consistent.

  This may include the following.

  o  if the dialog will be completely modal, call wind_update (BEG_MCTRL)
after wind_update (BEG_UPDATE).  When the dialog is complete, call wind_update
(END_MCTRL) and wind_update (END_UPDATE).

  o  Find the mouse cursor using events, do not poll the mouse location.  To
provide "hot"-objects use mouse "rectangle" events.

  o  If you put your dialog in a window, the "closer" should be the same as
CANCEL or ABORT.  The "mover" should allow moving the dialog.  If you want
the dialog to be partially modal, then top the dialog window instead of other
windows when you recieve a window top message and disable your menu bar.  In
either case, you main evnt_multi() code should handle dialog interaction with
objc_edit and objc_find and related calls.  Either be sure your window is
topped (only 1 rectangle - check while in wind_update) or walk rectangles.
Obviously, user interaction should not be handled while in any sort of wind_
update as window dialogs are windows that have objc_draw as a redraw.

  o  Fully non-modal dialogs are difficult on both the programmer and the
user.  Some possibilities would be a font-selection dialog, where the user
could change fonts with the dialog and edit the document at the same time.
In these cases, OK doesn't have to end the dialog, just make the proper change
in the document, and the closer removes the dialog.

  o  The new TOOLBAR settings may make dialog handling a bit easier.  It
handles the redraw (usually) and send you messages when the user clicks a
button.


Alert Boxes :
-------------

  Alerts should follow all the rules of dialog boxes, plus these additional
guidelines and suggestions.

  o  Whenever possible provide the user with more than one exit button

  o  Never provide both an OK button and a CANCEL button when both will
lead to the same action/inaction.

  o  Avoid using the word "error" or any term which may blame the user.

  o  If an error has occured, suggest a remedy.

  o  Use 'Cannot' instead of "Can not' or 'Can't"

  o  If an alert might occur while another application has focus, then
the first line of the alert text should be the program name, followed by
a colon ':'

  o  A message such as 'Not enough memory to load file TEST.DOC' is more
informative than 'Insufficient memory'.

  o  Minor warnings may be increasingly apparent, by ringing the system bell
at the first occurance and displaying a dialog box to guide the user on the
next occurance.

  o  Message Text should be left aligned.

  o  If a message cannot fit into 5 lines x 30 characters, either downsize
the alert for clarity, or place it in a longer form.  Do NOT use consecutive
alerts.

  o  Alerts should be capatalized by standard grammatical rules, and should
end in a question mark or period, never an exclamation point.

  Icons are to be used as follows :

  0  For credits, reminders and help
  1  Error Conditions or conditions requiring immediate attension
  2  Inquiries and most confirmations
  3  Potentially Program Fatal errors, confirmation of an irreversible action
  4  Informational Alert, with just an OK (if you don't have it, use 0)
  5  General Disk Errors and Requests (if you don't have it, use 1)


Since, I'm on a roll .. lemme cover mouse forms and the right mouse button


MOUSE FORMS
===========

  Change to the appropriate mouse form whenever you get the following
messages :  WM_TOPPED or WM_ONTOP.

  Mouse forms and my suggestions:

  0    ARROW        General Purpose Shape
  1    TEXT_CRSR    Application expects text entry into this object
  2    BUSY_BEE     Application is doing heavy calculations/disk access
  3    POINT_HAND   You are resizing the object
  4    FLAT_HAND    You are grabbing/moving the object
  5    THIN_CROSS   For "setting" points, such as a CAD or DTP application
  6    THICK_CROSS  For selecting from a large menu, like a dialing directory
  7    OUTLN_CROSS  For selecting blocks of text or spreadsheet cells.
  255  USER_DEF     For paint program brushes, special program "modes", such
                    as a help mode, etc.
  256  M_OFF        Remove mouse from screen (for updates).
  257  M_ON         Display the mouse cursor (reverse of above).
  258  M_SAVE       Saves current mouse form
  259  M_RESTORE    Restore saved mouse form  (*)
  260  M_LAST       Restore last mouse form   (*)

(*) These 2 entries were reversed in the ATARI Compendium, so that
M_RESTORE was 260, and M_LAST was 259.  I have kept the original descriptions
with the numbers, hoping these are correct.  The Compendium is obviously
mixed up, but I'm only guessing on the correct formats.


MULTIPLE BUTTONS
================

  The right mouse button should be used as follows when clicked on :

  o  An icon, or similar object :  Display a pop-up menu to let the user
  open, delete, hide, or show_info about the object.  The actual menu
  items are NOT significant, the fact that it calls a menu of actions
  for the object IS.  This can be a VERY helpful feature in object oriented
  applications (ever use Myriad Desktop?)

  o  Open Desktop :  Construct a pop-up menu identicle to the GEM menu-bar
  only vertical instead of horizontal and the top line should contain the
  application name (like the desk menu). Attach the GEM menus as cascading
  menus to this one, using the right arrow as normal.  If these menus in
  turn have a sub-menu, then continue the cascade as needed, like a NeXT or
  XWindows or something similar.  The user gains extra flexibility since
  every menu available up top becomes available on any blank desktop space,
  so users of big-screen monitors can trade some extra desktop space for
  easier access to the menus.  Note that it may not be possible to re-create
  the "desk menu" and allow the user to switch apps, but it would be nice.
  Can we implement our own GEM message for this?  Just make the app top
  a window and it will get the key focus, but how?

  o  In A Window :  If the window has its own menu bar, then you have 3
  options, otherwise you have 2.  If it has its own menu bar, the programmer
  may implement the same vertical menu as for the desktop window.  Otherwise,
  the programmer may display a contect-specific menu, or allow the user to
  "drag" the document in real-time around the window (like GEM-View).

  o  Special :  In some applications where the user selects between multiple
  tools with the left mouse button, it may be nice to allow the user to
  select a tool with the right or middle mouse buttons to "assign" the tool
  to that button.  The user could then work with multiple tools and save
  time by not switching tools as often.  Paint, DTP, and CAD programs could
  all benefit greatly from this.  Oh, you CAN connect a 3 button mouse to
  the ST.  If you want details, lemme know.  You can also emulate the 3rd
  mouse button.  Note that when you do this, a popup for the tool is no
  longer available for information about the tool, so a "help mode" should
  be provided.  Shift-HELP enters help mode, the mouse is changed to a
  question mark, and the user recieves help on any object he clicks on,
  then Shift-HELP will turn off help mode to resume normal operation.  You
  could also have the right mouse button give help on a tool, and have the
  left one select a tool.  I think a hot-help function (like Calamus) would
  be best allowing the user to assign tools to any mouse button.  Toolbars
  in any case, should be set as UNTOPPABLE.

  I do not know of other uses for a middle button other than that described
  above under the heading "Special".  There are certainly other uses for
  right and/or middle buttons, but I have many other uses to be confusing
  such as "mode switching" or access to background windows (normally with
  a CONTROL-Left CLICK, not a right click please).


===========================================================================

NOTE:  All user options and selections should be saveable!  Don't make the
user reset ANYTHING until he/she wants it changed.  All options should
be permanent even when the program ends and is re-executed.